Problem

Phase 1 + Phase 2 of the Server SDK Feature Flag Evaluations RFC for the JVM posthog-server package. Companion to the Node SDK PR (PostHog/posthog-js#3476) and the Python SDK PR (PostHog/posthog-python#539).

Today every flag check on posthog-server fires its own /flags request, and capture(appendFeatureFlags = true) silently fires yet another on every captured event. The flag values on a captured event can diverge from the ones the code actually branched on when person/group properties differ between calls. appendFeatureFlags also attaches every evaluated flag to every event, which bloats properties on high-volume events.

Tracking RFC: requests-for-comments-internal#1020.

Changes

New API (Phase 1)

postHog.evaluateFlags(distinctId, …) returns a PostHogFeatureFlagEvaluations snapshot:

val flags = postHog.evaluateFlags(distinctId, personProperties = mapOf("plan" to "enterprise"))
if (flags.isEnabled("new-dashboard")) {
    renderNewDashboard()
}
postHog.capture(distinctId, "page_viewed", flags = flags)

A single /flags request powers both branching and event enrichment. isEnabled() and getFlag() fire $feature_flag_called events (deduped through the existing per-distinct-id LRU) with the full metadata — $feature_flag_id, $feature_flag_version, $feature_flag_reason, $feature_flag_request_id, $feature_flag_error, plus $feature_flag_definitions_loaded_at for locally-evaluated flags — so experiment exposure tracking keeps working.

Java callers get a PostHogEvaluateFlagsOptions.builder() analogue alongside the Kotlin named-args entry point:

PostHogFeatureFlagEvaluations flags = postHog.evaluateFlags(
    "user-123",
    PostHogEvaluateFlagsOptions.builder()
        .personProperty("plan", "enterprise")
        .flagKeys(List.of("new-dashboard"))
        .build()
);

Two layers of scoping

• Network-level (flagKeys option): scopes the underlying /flags request itself. Goes into the request body as flag_keys_to_evaluate.

  val flags = postHog.evaluateFlags(distinctId, flagKeys = listOf("new-dashboard", "checkout-flow"))

• Event-level (filter helpers): narrow which flags get attached to a captured event without re-fetching.

  postHog.capture(distinctId, "page_viewed", flags = flags.onlyAccessed())
  postHog.capture(distinctId, "page_viewed", flags = flags.only(listOf("new-dashboard")))

Both onlyAccessed() and only(...) clone the snapshot with their own accessed set so filtered views don't back-propagate into the parent.

Deprecations (Phase 2)

The legacy single-flag surface keeps working but is now @Deprecated:

• isFeatureEnabled(...)
• getFeatureFlag(...)
• getFeatureFlagPayload(...)
• getFeatureFlagResult(...)
• capture(appendFeatureFlags = true) — emits a one-line deprecation log at runtime when truthy (Kotlin can't deprecate a single parameter value at compile time)

Each @Deprecated annotation includes a message pointing at evaluateFlags(...). Phase 3 (removal in next major) ships separately.

New config option

PostHogConfig.featureFlagsLogWarnings (default true) — set to false to silence the warnings emitted by the onlyAccessed() (empty-access fallback) and only(...) (unknown-key drop) filter helpers. Useful for callers who use those helpers conditionally.

Other request-body additions

evaluateFlags(...) also takes disableGeoip = true to forward geoip_disable into the /flags request body, parallel to the option that already exists in posthog-node and posthog-python.

Local evaluation

Transparent. When the poller resolves a flag, the snapshot carries locally_evaluated = true, reason "Evaluated locally", and $feature_flag_definitions_loaded_at is plumbed through, matching what the per-flag local path emits today.

Backwards compatibility

No breaking changes. All existing call paths return the same values they did before. Kotlin callers see a @Deprecated compile-time warning (silenceable with @Suppress("DEPRECATION")); the appendFeatureFlags = true runtime log goes through the standard config logger.

Internals

PostHogStateless.sendFeatureFlagCalled is split into captureFeatureFlagCalledEvent, which is shared between the per-flag accessor path and the new snapshot. Both paths now dedupe identically against the same PostHogFeatureFlagCalledCache LRU. The single-flag path also picks up $feature_flag_id / $feature_flag_version / $feature_flag_reason here — previously only the Android client emitted those, server SDK was missing them.

A small EvaluationsHost interface is what the snapshot calls back into, instead of holding a reference to the full client — keeps the snapshot easy to test in isolation with a fake host.

Response-level errors (errors_while_computing_flags, quota_limited) are propagated into snapshot $feature_flag_called events via EvaluateFlagsResult.responseError, matching the granularity of the per-flag path.

A new getFeatureFlagDetails(...) default method on PostHogFeatureFlagsInterface (returns null by default) lets the server SDK expose the cached FeatureFlag to the per-flag path without changing existing implementations.

Docs: posthog-server/USAGE.md updated with a Kotlin + Java example of the snapshot flow and the flagKeys vs only(...) distinction.

Tests

Two test files cover snapshot semantics and end-to-end flow:

• PostHogFeatureFlagEvaluationsTest — snapshot accessors, full metadata on captures, filter helpers, onlyAccessed() empty-fallback warning, only(...) unknown-key warning, parent/child filter isolation, blank-distinctId no-op, locally-evaluated tagging, response-error propagation, featureFlagsLogWarnings = false host suppression.
• PostHogEvaluateFlagsTest — end-to-end via MockWebServer: single /flags round-trip, no events fire before access, dedup across access, getFlagPayload no-event, capture(flags=…) doesn't issue a second request, flag_keys_to_evaluate body forwarding, blank-distinctId short-circuit, local evaluation tagging, quota_limited propagation, appendFeatureFlags = true deprecated path still works end-to-end.

./gradlew :posthog-server:check :posthog:check (tests + lint + apiCheck + animalsniffer) clean.

Created with PostHog Code